{ "cells": [ { "cell_type": "markdown", "id": "f20d04c8-b67e-49f6-8236-df75f52049af", "metadata": {}, "source": [ "# ANISE\n", "\n", "ANISE is a modern rewrite of NAIF SPICE, written in Rust and providing interfaces to other languages including Python.\n", "\n", "Evidently, this tutorial applies to the Python usage of ANISE.\n", "\n", "## Goal\n", "By the end of this tutorial, you should know how to build a data frame containing the Azimuth, Elevation, and Range data from a location from any body fixed object (like an Earth ground station) and another other object stored in the almanac.\n", "\n", "Let's start by installing ANISE: `pip install anise`" ] }, { "cell_type": "markdown", "id": "645bb375-58da-42a2-8107-2af6bbb38b5f", "metadata": {}, "source": [ "## Loading the latest orientation and planetary data\n", "\n", "In this tutorial, we're using the latest Earth orientation parameters from JPL, and the latest planetary ephemerides, constants, and high precision Moon rotation parameters. These can be downloaded automatically by ANISE using the MetaAlmanac class (refer to tutorial #02 for details)." ] }, { "cell_type": "code", "execution_count": 1, "id": "b594d869-f456-4f8a-a6e5-72a0e3050f5e", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "Almanac: #SPK = 1\t#BPC = 2\tPlanetaryData with 54 ID mappings and 0 name mappings\tEulerParameterData with 3 ID mappings and 3 name mappings (@0x5638ac745070)" ] }, "execution_count": 1, "metadata": {}, "output_type": "execute_result" } ], "source": [ "from anise import MetaAlmanac\n", "\n", "almanac = MetaAlmanac.latest()\n", "\n", "almanac" ] }, { "cell_type": "markdown", "id": "8933c0a3-0530-43ec-a332-39b5f35869b0", "metadata": {}, "source": [ "Superb! We've got two BPCs loaded (the latest Earth and the long-term Moon high precision rotation), the DE440s planetary ephemerides, and planetary constants for 49 objects in the solar system." ] }, { "cell_type": "markdown", "id": "38ce5bee-bb5b-4bbc-9e9e-125faf6aa1e7", "metadata": {}, "source": [ "## Defining a ground station\n", "\n", "Let's define a ground station in Madrid, Spain (for example). We start by importing the Orbit structure, and figure out how it could be initialized for a ground asset." ] }, { "cell_type": "code", "execution_count": 2, "id": "788f43ca-b56a-4737-9088-b40424b81fe5", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "\u001b[0;31mSignature:\u001b[0m\n", "\u001b[0mOrbit\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mfrom_latlongalt\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mlatitude_deg\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mlongitude_deg\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mheight_km\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mangular_velocity\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mepoch\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m \u001b[0mframe\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n", "\u001b[0;34m\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n", "\u001b[0;31mDocstring:\u001b[0m\n", "Creates a new Orbit from the latitude (φ), longitude (λ) and height (in km) with respect to the frame's ellipsoid given the angular velocity.\n", "\n", "**Units:** degrees, degrees, km, rad/s\n", "NOTE: This computation differs from the spherical coordinates because we consider the flattening of body.\n", "Reference: G. Xu and Y. Xu, \"GPS\", DOI 10.1007/978-3-662-50367-6_2, 2016\n", "\u001b[0;31mType:\u001b[0m builtin_function_or_method" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "from anise.astro import Orbit\n", "Orbit.from_latlongalt?" ] }, { "cell_type": "code", "execution_count": 3, "id": "8ca5609a-2751-4f8e-8182-09f8769d0037", "metadata": {}, "outputs": [], "source": [ "# Define the location of the asset\n", "# Build the Madrid DSN gound station\n", "latitude_deg = 40.427_222\n", "longitude_deg = 4.250_556\n", "height_km = 0.834_939\n", "\n", "# As noted in the documentation, this call also requires the mean angular velocity of the reference frame.\n", "# Source: G. Xu and Y. Xu, \"GPS\", DOI 10.1007/978-3-662-50367-6_2, 2016 (confirmed by https://hpiers.obspm.fr/eop-pc/models/constants.html)\n", "MEAN_EARTH_ANGULAR_VELOCITY_DEG_S = 0.004178079012116429" ] }, { "cell_type": "markdown", "id": "f82e4205-8a5f-4ec6-8b55-d6e4df854631", "metadata": {}, "source": [ "## Defining the frame and epoch" ] }, { "cell_type": "code", "execution_count": 4, "id": "13fd331a-f32b-4e23-a326-1dcd0a671586", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "Earth ITRF93 (μ = 398600.435436096 km^3/s^2, eq. radius = 6378.1366 km, polar radius = 6356.7519 km, f = 0.0033528131084554717) (@0x7f64028c6e80)" ] }, "execution_count": 4, "metadata": {}, "output_type": "execute_result" } ], "source": [ "from anise.astro.constants import Frames\n", "from anise.time import *\n", "\n", "# Grab the high precision Earth rotation frame (ITRF93)\n", "itrf93 = almanac.frame_info(Frames.EARTH_ITRF93)\n", "itrf93" ] }, { "cell_type": "markdown", "id": "f632778f-4792-462f-bb83-88abba8f788a", "metadata": {}, "source": [ "We now have everything to initialize the ground asset, apart from the epoch. So let's define a time series to compute the AER of the (center) of the Moon throughout a month. " ] }, { "cell_type": "code", "execution_count": 5, "id": "0b0c35b5-ee36-4313-8b81-6194e8ede907", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "TimeSeries { start: 2023-01-01T20:00:00 UTC, duration: Duration { centuries: 0, nanoseconds: 2592000000000000 }, step: Duration { centuries: 0, nanoseconds: 60000000000 }, cur: 0, incl: true } @ 0x7f64032ba1a0" ] }, "execution_count": 5, "metadata": {}, "output_type": "execute_result" } ], "source": [ "start = Epoch(\"2023-01-01 20:00:00\")\n", "end = start + Unit.Day*30\n", "step = Unit.Minute*1\n", "\n", "time_series = TimeSeries(start, end, step, inclusive=True)\n", "time_series" ] }, { "cell_type": "markdown", "id": "54310bd7-f573-4436-b135-18a18baba32f", "metadata": {}, "source": [ "## Generate the AER data\n", "Now, we just need to iterate over this time series, storing the AER result in an array for each computation.\n", "\n", "Note that the nomenclature used in the AER computation is \"receiver\" and \"transmitter\", which is the typical convention for orbit determination, a capability enabled by the Nyx astrodynamics package, a superset of ANISE." ] }, { "cell_type": "code", "execution_count": 6, "id": "fe9a2311-eb16-43f6-8e83-f9daacd13ec2", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "\u001b[0;31mSignature:\u001b[0m \u001b[0malmanac\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mazimuth_elevation_range_sez\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mrx\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mtx\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n", "\u001b[0;31mDocstring:\u001b[0m\n", "Computes the azimuth (in degrees), elevation (in degrees), and range (in kilometers) of the\n", "receiver state (`rx`) seen from the transmitter state (`tx`), once converted into the SEZ frame of the transmitter.\n", "\n", "# Algorithm\n", "1. Compute the SEZ (South East Zenith) frame of the transmitter.\n", "2. Rotate the receiver position vector into the transmitter SEZ frame.\n", "3. Rotate the transmitter position vector into that same SEZ frame.\n", "4. Compute the range as the norm of the difference between these two position vectors.\n", "5. Compute the elevation, and ensure it is between +/- 180 degrees.\n", "6. Compute the azimuth with a quadrant check, and ensure it is between 0 and 360 degrees.\n", "\u001b[0;31mType:\u001b[0m builtin_function_or_method" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "almanac.azimuth_elevation_range_sez?" ] }, { "cell_type": "code", "execution_count": 7, "id": "a394f90a-be4a-412b-8fb1-ac7d7f8347f0", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "\u001b[0;31mSignature:\u001b[0m \u001b[0malmanac\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mtransform\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mtarget_frame\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mobserver_frame\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mepoch\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mab_corr\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0;32mNone\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n", "\u001b[0;31mDocstring:\u001b[0m\n", "Returns the Cartesian state needed to transform the `from_frame` to the `to_frame`.\n", "\n", "# SPICE Compatibility\n", "This function is the SPICE equivalent of spkezr: `spkezr(TARGET_ID, EPOCH_TDB_S, ORIENTATION_ID, ABERRATION, OBSERVER_ID)`\n", "In ANISE, the TARGET_ID and ORIENTATION are provided in the first argument (TARGET_FRAME), as that frame includes BOTH\n", "the target ID and the orientation of that target. The EPOCH_TDB_S is the epoch in the TDB time system, which is computed\n", "in ANISE using Hifitime. THe ABERRATION is computed by providing the optional Aberration flag. Finally, the OBSERVER\n", "argument is replaced by OBSERVER_FRAME: if the OBSERVER_FRAME argument has the same orientation as the TARGET_FRAME, then this call\n", "will return exactly the same data as the spkerz SPICE call.\n", "\n", "# Note\n", "The units will be those of the underlying ephemeris data (typically km and km/s)\n", "\u001b[0;31mType:\u001b[0m builtin_function_or_method" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "# Import the aberration correction because we want to correct for the light time.\n", "from anise import Aberration\n", "# Checking the doc is always helpful!\n", "almanac.transform?" ] }, { "cell_type": "code", "execution_count": 8, "id": "b93ab05e-a27f-4b18-9ad9-d74746609e45", "metadata": {}, "outputs": [], "source": [ "aer_data = []\n", "\n", "for epoch in time_series:\n", " # Build the observer (\"transmitter\") at this epoch\n", " tx = Orbit.from_latlongalt(latitude_deg, longitude_deg, height_km, MEAN_EARTH_ANGULAR_VELOCITY_DEG_S, epoch, itrf93)\n", " # Grab the state of the Moon at this epoch (\"receiver\")\n", " rx = almanac.transform(Frames.MOON_J2000, Frames.EARTH_J2000, epoch, Aberration(\"LT+S\"))\n", " # NOTE: The rx state here is in the Earth J2000 frame, but that's OK because the Almanac will compute the translations needed.\n", " this_aer = almanac.azimuth_elevation_range_sez(rx, tx)\n", " aer_data += [this_aer]" ] }, { "cell_type": "markdown", "id": "cfb78d25-d1d5-47b8-8272-9c1081917bb9", "metadata": {}, "source": [ "## Plotting the data\n", "\n", "Let's build a Polars dataframe with the AER data and plot it using `hvplot` (the recommended tool by Polars). We're using Polars here because it's dozens of times faster than Pandas, and we've got ~43k rows in our data set, so we might as well filter through it quickly.\n", "\n", "Let's install Polars (with the plotting option) and hvplot." ] }, { "cell_type": "code", "execution_count": 11, "id": "302ef0b8-370b-43ad-92e5-3e77431dd63d", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Requirement already satisfied: polars[plot] in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (0.20.4)\n", "Requirement already satisfied: hvplot in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (0.9.1)\n", "Requirement already satisfied: bokeh>=1.0.0 in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from hvplot) (3.3.3)\n", "Requirement already satisfied: colorcet>=2 in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from hvplot) (3.0.1)\n", "Requirement already satisfied: holoviews>=1.11.0 in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from hvplot) (1.18.1)\n", "Requirement already satisfied: pandas in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from hvplot) (2.1.4)\n", "Requirement already satisfied: numpy>=1.15 in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from hvplot) (1.26.3)\n", "Requirement already satisfied: packaging in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from hvplot) (23.2)\n", "Requirement already satisfied: panel>=0.11.0 in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from hvplot) (1.3.6)\n", "Requirement already satisfied: param<3.0,>=1.12.0 in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from hvplot) (2.0.1)\n", "Requirement already satisfied: Jinja2>=2.9 in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from bokeh>=1.0.0->hvplot) (3.1.2)\n", "Requirement already satisfied: contourpy>=1 in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from bokeh>=1.0.0->hvplot) (1.2.0)\n", "Requirement already satisfied: pillow>=7.1.0 in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from bokeh>=1.0.0->hvplot) (10.2.0)\n", "Requirement already satisfied: PyYAML>=3.10 in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from bokeh>=1.0.0->hvplot) (6.0.1)\n", "Requirement already satisfied: tornado>=5.1 in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from bokeh>=1.0.0->hvplot) (6.4)\n", "Requirement already satisfied: xyzservices>=2021.09.1 in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from bokeh>=1.0.0->hvplot) (2023.10.1)\n", "Requirement already satisfied: pyct>=0.4.4 in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from colorcet>=2->hvplot) (0.5.0)\n", "Requirement already satisfied: pyviz-comms>=0.7.4 in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from holoviews>=1.11.0->hvplot) (3.0.0)\n", "Requirement already satisfied: python-dateutil>=2.8.2 in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from pandas->hvplot) (2.8.2)\n", "Requirement already satisfied: pytz>=2020.1 in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from pandas->hvplot) (2023.3.post1)\n", "Requirement already satisfied: tzdata>=2022.1 in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from pandas->hvplot) (2023.4)\n", "Requirement already satisfied: markdown in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from panel>=0.11.0->hvplot) (3.5.2)\n", "Requirement already satisfied: markdown-it-py in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from panel>=0.11.0->hvplot) (3.0.0)\n", "Requirement already satisfied: linkify-it-py in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from panel>=0.11.0->hvplot) (2.0.2)\n", "Requirement already satisfied: mdit-py-plugins in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from panel>=0.11.0->hvplot) (0.4.0)\n", "Requirement already satisfied: requests in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from panel>=0.11.0->hvplot) (2.31.0)\n", "Requirement already satisfied: tqdm>=4.48.0 in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from panel>=0.11.0->hvplot) (4.66.1)\n", "Requirement already satisfied: bleach in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from panel>=0.11.0->hvplot) (6.1.0)\n", "Requirement already satisfied: typing-extensions in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from panel>=0.11.0->hvplot) (4.6.3)\n", "Requirement already satisfied: MarkupSafe>=2.0 in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from Jinja2>=2.9->bokeh>=1.0.0->hvplot) (2.1.3)\n", "Requirement already satisfied: six>=1.5 in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from python-dateutil>=2.8.2->pandas->hvplot) (1.16.0)\n", "Requirement already satisfied: webencodings in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from bleach->panel>=0.11.0->hvplot) (0.5.1)\n", "Requirement already satisfied: uc-micro-py in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from linkify-it-py->panel>=0.11.0->hvplot) (1.0.2)\n", "Requirement already satisfied: mdurl~=0.1 in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from markdown-it-py->panel>=0.11.0->hvplot) (0.1.2)\n", "Requirement already satisfied: charset-normalizer<4,>=2 in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from requests->panel>=0.11.0->hvplot) (3.3.2)\n", "Requirement already satisfied: idna<4,>=2.5 in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from requests->panel>=0.11.0->hvplot) (3.6)\n", "Requirement already satisfied: urllib3<3,>=1.21.1 in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from requests->panel>=0.11.0->hvplot) (2.1.0)\n", "Requirement already satisfied: certifi>=2017.4.17 in /home/chris/Workspace/nyx-space/anise/anise-py/.venv/lib64/python3.11/site-packages (from requests->panel>=0.11.0->hvplot) (2023.11.17)\n", "\n", "\u001b[1m[\u001b[0m\u001b[34;49mnotice\u001b[0m\u001b[1;39;49m]\u001b[0m\u001b[39;49m A new release of pip is available: \u001b[0m\u001b[31;49m23.1.2\u001b[0m\u001b[39;49m -> \u001b[0m\u001b[32;49m24.0\u001b[0m\n", "\u001b[1m[\u001b[0m\u001b[34;49mnotice\u001b[0m\u001b[1;39;49m]\u001b[0m\u001b[39;49m To update, run: \u001b[0m\u001b[32;49mpip install --upgrade pip\u001b[0m\n", "Note: you may need to restart the kernel to use updated packages.\n" ] } ], "source": [ "%pip install \"polars[plot]\" hvplot" ] }, { "cell_type": "markdown", "id": "2400ac97-6a46-47cf-a3ac-ad85672469ee", "metadata": {}, "source": [ "Now, let's build a data frame. As of January 2024, we need some custom handling of the epochs in Hifitime to make them compatible with Python's lower precision datetime object, but this will be fixed in [this hifitime issue](https://github.com/nyx-space/hifitime/issues/185)." ] }, { "cell_type": "code", "execution_count": 13, "id": "2de60a1a-27c9-461d-8bf6-c430b951ca8a", "metadata": {}, "outputs": [ { "data": { "text/html": [ "
| describe | epochs | elevation_deg | azimuth_deg | range_km | range_rate_km_s |
|---|---|---|---|---|---|
| str | str | f64 | f64 | f64 | f64 |
| "count" | "43201" | 43201.0 | 43201.0 | 43201.0 | 43201.0 |
| "null_count" | "0" | 0.0 | 0.0 | 0.0 | 0.0 |
| "mean" | null | 1.920361 | 179.943419 | 385666.088874 | 0.009381 |
| "std" | null | 36.571063 | 98.443342 | 16472.238106 | 13.798014 |
| "min" | "2023-01-01 20:… | -77.166677 | 0.005663 | 354094.280434 | -20.694402 |
| "25%" | null | -25.144 | 92.887676 | 370637.2144 | -13.742085 |
| "50%" | null | 1.205067 | 180.070913 | 390142.67677 | -0.0035 |
| "75%" | null | 29.304787 | 266.940744 | 399983.931307 | 13.763225 |
| "max" | "2023-01-31 20:… | 76.760723 | 359.975421 | 409264.590342 | 20.698013 |